Untitled Document

1. Standard Utility Functions (`stdlib.h')
2. Character Type Macros and Functions (`ctype.h')
3. Input and Output (`stdio.h')

4. Strings and Memory (`string.h')
5. Wide Character Strings (`wchar.h')
6. Signal Handling (`signal.h')

7. Time Functions (`time.h')
8. Locale (`locale.h')
11. System Calls

10. Miscellaneous Macros and Functions
12. Variable Argument Lists
9. Reentrancy

Index

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

1.1 abort---abnormal termination of a program		Abnormal termination of a program
1.2 abs---integer absolute value (magnitude)		Integer absolute value (magnitude)
1.3 assert---Macro for Debugging Diagnostics		Macro for Debugging Diagnostics
1.4 atexit---request execution of functions at program exit		Request execution of functions at program exit
1.5 atof, atoff---string to double or float		String to double or float
1.6 atoi, atol---string to integer		String to integer
1.7 atoll---convert a string to a long long integer		String to long long
1.8 calloc---allocate space for arrays		Allocate space for arrays
1.9 div---divide two integers		Divide two integers
1.12 ecvtbuf, fcvtbuf---double or float to string		Double or float to string of digits
1.10 ecvt,ecvtf,fcvt,fcvtf---double or float to string		Double or float to string of digits (malloc result)
1.13 __env_lock, __env_unlock--lock environ variable		Lock environment list for getenv and setenv
1.11 gvcvt, gcvtf---format double or float as string		Format double or float as string
1.14 exit---end program execution		End program execution
1.15 getenv---look up environment variable		Look up environment variable
1.16 labs---long integer absolute value		Long integer absolute value (magnitude)
1.17 ldiv---divide two long integers		Divide two long integers
1.18 llabs---compute the absolute value of an long long integer.		Long long integer absolute value (magnitude)
1.19 lldiv---divide two long long integers		Divide two long long integers
1.20 malloc, realloc, free---manage memory		Allocate and manage memory (malloc, realloc, free)
1.21 mallinfo, malloc_stats, mallopt--malloc support		Get information about allocated memory
1.22 __malloc_lock, __malloc_unlock--lock malloc pool		Lock memory pool for malloc and free
1.24 mbstowcs---minimal multibyte string to wide char converter		Minimal multibyte string to wide string converter
1.23 mblen---minimal multibyte length function		Minimal multibyte length
1.25 mbtowc---minimal multibyte to wide char converter		Minimal multibyte to wide character converter
1.26 rand, srand---pseudo-random numbers		Pseudo-random numbers
1.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines		Uniformly distributed pseudo-random numbers
1.28 strtod, strtof---string to double or float		String to double or float
1.29 strtol---string to long		String to long
1.30 strtoul---string to unsigned long		String to unsigned long
1.31 system---execute command string		Execute command string
1.32 wcstombs---minimal wide char string to multibyte string converter		Minimal wide string to multibyte string converter
1.33 wctomb---minimal wide char to multibyte converter		Minimal wide character to multibyte converter

1.1 abort---abnormal termination of a program

#include <stdlib.h>
void abort(void);

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

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

Returns
abort does not return to its caller.

Portability
ANSI C requires abort.

Supporting OS subroutines required: _exit and optionally, write.

1.2 abs---integer absolute value (magnitude)

#include <stdlib.h>
int abs(int 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.

1.3 assert---Macro for Debugging Diagnostics

#include <assert.h>
void assert(int expression);

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.

1.4 atexit---request execution of functions at program exit

#include <stdlib.h>
int atexit (void (*function)(void));

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.

1.5 atof, atoff---string to double or float

#include <stdlib.h>
double atof(const char *s);
float atoff(const char *s);

The functions parse the character string s, locating a substring which can be converted to a floating-point value. The substring must match the format:

[+|-]digits[.][digits][(e|E)[+|-]digits]

The substring converted is the longest initial fragment of s that has the expected format, beginning with the first non-whitespace character. The substring is empty if str is empty, consists entirely of whitespace, or if the first non-whitespace character is something other than +, -, ., or a digit.

atof(s) is implemented as strtod(s, NULL). atoff(s) is implemented as strtof(s, NULL).

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

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

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

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

1.6 atoi, atol---string to integer

#include <stdlib.h>
int atoi(const char *s);
long atol(const char *s);
int _atoi_r(struct _reent *ptr, const char *s);
long _atol_r(struct _reent *ptr, const char *s);

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

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

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

Portability
atoi, atol are ANSI.

No supporting OS subroutines are required.

1.7 atoll---convert a string to a long long integer

#include <stdlib.h>
long long atoll(const char *str);
long long _atoll_r(struct _reent *ptr, const char *str);

The alternate function _atoll_r is a reentrant version. The extra argument reent is a pointer to a reentrancy structure.

Returns
The converted value.

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

No supporting OS subroutines are required.

1.8 calloc---allocate space for arrays

#include <stdlib.h>
void *calloc(size_t n, size_t s);
void *calloc_r(void *reent, size_t <n>, <size_t> s);

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

The alternate function _calloc_r is reentrant. The extra argument reent is a pointer to a reentrancy structure.

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

If unsuccessful, NULL.

Portability
calloc is ANSI.

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

1.9 div---divide two integers

#include <stdlib.h>
div_t div(int n, int d);

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.

1.10 ecvt,ecvtf,fcvt,fcvtf---double or float to string

#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);

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

1.11 gvcvt, gcvtf---format double or float as string

#include <stdlib.h>

char *gcvt(double val, int precision, char *buf);
char *gcvtf(float val, int precision, char *buf);

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.

1.12 ecvtbuf, fcvtbuf---double or float to string

#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);

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.

1.13 __env_lock, __env_unlock--lock environ variable

#include "envlock.h"
void __env_lock (struct _reent *reent);
void __env_unlock (struct _reent *reent);

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

1.14 exit---end program execution

#include <stdlib.h>
void exit(int code);

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.

1.15 getenv---look up environment variable

#include <stdlib.h>
char *getenv(const char *name);

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.

1.16 labs---long integer absolute value

#include <stdlib.h>
long labs(long 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.

1.17 ldiv---divide two long integers

#include <stdlib.h>
ldiv_t ldiv(long n, long d);

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.

1.18 llabs---compute the absolute value of an long long integer.

#include <stdlib.h>
long long llabs(long long j);

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

Returns
A nonnegative long long integer.

Portability
llabs is ISO 9899 (C99) compatable.

No supporting OS subroutines are required.

1.19 lldiv---divide two long long integers

#include <stdlib.h>
lldiv_t lldiv(long long n, long long d);

Returns
The result is represented with the structure

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

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

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

Portability
lldiv is ISO 9899 (C99) compatable.

No supporting OS subroutines are required.

1.20 malloc, realloc, free---manage memory

#include <stdlib.h>
void *malloc(size_t nbytes);
void *realloc(void *aptr, size_t nbytes);
void free(void *aptr);

void *memalign(size_t align, size_t nbytes);

size_t malloc_usable_size(void *aptr);

void *_malloc_r(void *reent, size_t nbytes);
void *_realloc_r(void *reent, 
    void *aptr, size_t nbytes);
void _free_r(void *reent, void *aptr);

void *_memalign_r(void *reent,
    size_t align, size_t nbytes);

size_t _malloc_usable_size_r(void *reent, void *aptr);

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 memalign function returns a block of size nbytes aligned to a align boundary. The align argument must be a power of two.

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

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

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

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

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

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

free does not return a result.

memalign returns a pointer to the newly allocated space.

malloc_usable_size returns the usable size.

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

memalign is part of SVR4.

malloc_usable_size is not portable.

Supporting OS subroutines required: sbrk.

1.21 mallinfo, malloc_stats, mallopt--malloc support

#include <malloc.h>
struct mallinfo mallinfo(void);
void malloc_stats(void);
int mallopt(int parameter, value);

struct mallinfo _mallinfo_r(void *reent);
void _malloc_stats_r(void *reent);
int _mallopt_r(void *reent, int parameter, value);

malloc_stats print some statistics about memory allocation on standard error.

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

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

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

malloc_stats does not return a result.

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

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

1.22 __malloc_lock, __malloc_unlock--lock malloc pool

#include <malloc.h>
void __malloc_lock (struct _reent *reent);
void __malloc_unlock (struct _reent *reent);

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

1.23 mblen---minimal multibyte length function

#include <stdlib.h>
int mblen(const char *s, size_t n);

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

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

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

mblen requires no supporting OS subroutines.

1.24 mbstowcs---minimal multibyte string to wide char converter

#include <stdlib.h>
int mbstowcs(wchar_t *pwc, const char *s, size_t n);

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

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

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

mbstowcs requires no supporting OS subroutines.

1.25 mbtowc---minimal multibyte to wide char converter

#include <stdlib.h>
int mbtowc(wchar_t *pwc, const char *s, size_t n);

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

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

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

mbtowc requires no supporting OS subroutines.

1.26 rand, srand---pseudo-random numbers

#include <stdlib.h>
int rand(void);
void srand(unsigned int seed);
int rand_r(unsigned int *seed);

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.

1.27 rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 --pseudo random number generators and initialization routines

#include <stdlib.h>
double drand48(void);
double erand48(unsigned short xseed[3]);
long lrand48(void);
long nrand48(unsigned short xseed[3]);
long mrand48(void);
long jrand48(unsigned short xseed[3]);
void srand48(long seed);
unsigned short *seed48(unsigned short xseed[3]);
void lcong48(unsigned short p[7]);

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

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

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

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

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

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

All functions share the same multiplicand and addend.

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

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

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

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

For a more powerful random number generator, see random.

Portability
SUS requires these functions.

No supporting OS subroutines are required.

1.28 strtod, strtof---string to double or float

#include <stdlib.h>
double strtod(const char *str, char **tail);
float strtof(const char *str, char **tail);

double _strtod_r(void *reent, 
    const char *str, char **tail);

[+|-]digits[.][digits][(e|E)[+|-]digits] 

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.

1.29 strtol---string to long

#include <stdlib.h>
long strtol(const char *s, char **ptr,int base);

long _strtol_r(void *reent, 
    const char *s, char **ptr,int base);

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.

1.30 strtoul---string to unsigned long

#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);

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.

1.31 system---execute command string

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

int _system_r(void *reent, char *s);

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.

1.32 wcstombs---minimal wide char string to multibyte string converter

#include <stdlib.h>
int wcstombs(const char *s, wchar_t *pwc, size_t n);

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

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

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

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

wcstombs requires no supporting OS subroutines.

1.33 wctomb---minimal wide char to multibyte converter

#include <stdlib.h>
int wctomb(char *s, wchar_t wchar);

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

Each call to wctomb modifies *s unless s is a null pointer or MB_CAPABLE is defined and wchar is invalid.

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

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

wctomb requires no supporting OS subroutines.

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

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

2.1 isalnum---alphanumeric character predicate		Alphanumeric character predicate
2.2 isalpha---alphabetic character predicate		Alphabetic character predicate
2.3 isascii---ASCII character predicate		ASCII character predicate
2.4 iscntrl---control character predicate		Control character predicate
2.5 isdigit---decimal digit predicate		Decimal digit predicate
2.6 islower---lower-case character predicate		Lower-case character predicate
2.7 isprint, isgraph---printable character predicates		Printable character predicates (isprint, isgraph)
2.8 ispunct---punctuation character predicate		Punctuation character predicate
2.9 isspace---whitespace character predicate		Whitespace character predicate
2.10 isupper---uppercase character predicate		Uppercase character predicate
2.11 isxdigit---hexadecimal digit predicate		Hexadecimal digit predicate
2.12 toascii---force integers to ASCII range		Force integers to ASCII range
2.13 tolower---translate characters to lower case		Translate characters to lower case
2.14 toupper---translate characters to upper case		Translate characters to upper case
2.15 iswalnum---alpha-numeric wide-character test		Alphanumeric wide-character predicate
2.16 iswalpha---alphabetic wide-character test		Alphabetic wide-character predicate
2.17 iswcntrl---wide-character cntrl test		Control wide-character predicate
2.18 iswdigit---decimal digit wide-character test		Decimal digit wide-character predicate
2.19 iswgraph---graphic wide-character test		Graphic wide-character predicate
2.20 iswlower---lower-case wide-character test		Lower-case wide-character predicate
2.21 iswprint---printable wide-character test		Printable wide-character predicate
2.22 iswpunct---punctuation wide-character test		Punctuation wide-character predicate
2.23 iswspace---wide-character space test		Whitespace wide-character predicate
2.24 iswupper---upper-case wide-character test		Uppercase wide-character predicate
2.25 iswxdigit---hexadecimal digit wide-character test		Hexadecimal digit wide-character predicate
2.26 iswctype---extensible wide-character test		Extensible wide-character test
2.27 wctype---get wide-character classification type		Compute wide-character test type
2.28 towlower---translate wide-characters to lower case		Translate wide-characters to lower case
2.29 towupper---translate wide-characters to upper case		Translate wide-characters to upper case
2.30 towctrans---extensible wide-character case mapping		Extensible wide-character case mapping
2.31 wctrans---get wide-character translation type		Compute wide-character translation type

2.1 isalnum---alphanumeric character predicate

#include <ctype.h>
int isalnum(int c);

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.

2.2 isalpha---alphabetic character predicate

#include <ctype.h>
int isalpha(int c);

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.

2.3 isascii---ASCII character predicate

#include <ctype.h>
int isascii(int c);

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.

2.4 iscntrl---control character predicate

#include <ctype.h>
int iscntrl(int c);

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.

2.5 isdigit---decimal digit predicate

#include <ctype.h>
int isdigit(int c);

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.

2.6 islower---lower-case character predicate

#include <ctype.h>
int islower(int c);

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.

2.7 isprint, isgraph---printable character predicates

#include <ctype.h>
int isprint(int c);
int isgraph(int c);

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.

2.8 ispunct---punctuation character predicate

#include <ctype.h>
int ispunct(int c);

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.

2.9 isspace---whitespace character predicate

#include <ctype.h>
int isspace(int c);

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.

2.10 isupper---uppercase character predicate

#include <ctype.h>
int isupper(int c);

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.

2.11 isxdigit---hexadecimal digit predicate

#include <ctype.h>
int isxdigit(int c);

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.

2.12 toascii---force integers to ASCII range

#include <ctype.h>
int toascii(int c);

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.

2.13 tolower---translate characters to lower case

#include <ctype.h>
int tolower(int c);
int _tolower(int c);

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.

2.14 toupper---translate characters to upper case

#include <ctype.h>
int toupper(int c);
int _toupper(int c);

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.

2.15 iswalnum---alpha-numeric wide-character test

#include <wctype.h>
int iswalnum(wint_t c);

Returns
iswalnum returns non-zero if c is a alpha-numeric wide-character.

Portability
iswalnum is C99.

No supporting OS subroutines are required.

2.16 iswalpha---alphabetic wide-character test

#include <wctype.h>
int iswalpha(wint_t c);

Returns
iswalpha returns non-zero if c is an alphabetic wide-character.

Portability
iswalpha is C99.

No supporting OS subroutines are required.

2.17 iswcntrl---wide-character cntrl test

#include <wctype.h>
int iswcntrl(wint_t c);

Returns
iswcntrl returns non-zero if c is a control wide-character.

Portability
iswcntrl is C99.

No supporting OS subroutines are required.

2.18 iswdigit---decimal digit wide-character test

#include <wctype.h>
int iswdigit(wint_t c);

Returns
iswdigit returns non-zero if c is a decimal digit wide-character.

Portability
iswdigit is C99.

No supporting OS subroutines are required.

2.19 iswgraph---graphic wide-character test

#include <wctype.h>
int iswgraph(wint_t c);

Returns
iswgraph returns non-zero if c is a graphic wide-character.

Portability
iswgraph is C99.

No supporting OS subroutines are required.

2.20 iswlower---lower-case wide-character test

#include <wctype.h>
int iswlower(wint_t c);

Returns
iswlower returns non-zero if c is a lower-case wide-character.

Portability
iswlower is C99.

No supporting OS subroutines are required.

2.21 iswprint---printable wide-character test

#include <wctype.h>
int iswprint(wint_t c);

Returns
iswprint returns non-zero if c is a printable wide-character.

Portability
iswprint is C99.

No supporting OS subroutines are required.

2.22 iswpunct---punctuation wide-character test

#include <wctype.h>
int iswpunct(wint_t c);

Returns
iswpunct returns non-zero if c is a punctuation wide-character.

Portability
iswpunct is C99.

No supporting OS subroutines are required.

2.23 iswspace---wide-character space test

#include <wctype.h>
int iswspace(wint_t c);

Returns
iswspace returns non-zero if c is a white-space wide-character.

Portability
iswspace is C99.

No supporting OS subroutines are required.

2.24 iswupper---upper-case wide-character test

#include <wctype.h>
int iswupper(wint_t c);

Returns
iswupper returns non-zero if c is a upper-case wide-character.

Portability
iswupper is C99.

No supporting OS subroutines are required.

2.25 iswxdigit---hexadecimal digit wide-character test

#include <wctype.h>
int iswxdigit(wint_t c);

Returns
iswxdigit returns non-zero if c is a hexadecimal digit wide-character.

Portability
iswxdigit is C99.

No supporting OS subroutines are required.

2.26 iswctype---extensible wide-character test

#include <wctype.h>
int iswctype(wint_t c, wctype_t desc);

Returns
iswctype returns non-zero if and only if c matches the test specified by desc. If desc is unknown, zero is returned.

Portability
iswctype is C99.

No supporting OS subroutines are required.

2.27 wctype---get wide-character classification type

#include <wctype.h>
wctype_t wctype(const char *c);

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

Portability
wctype is C99.

No supporting OS subroutines are required.

2.28 towlower---translate wide-characters to lower case

#include <wctype.h>
wint_t towlower(wint_t c);

Returns
towlower returns the lower-case equivalent of c when it is a upper-case wide-character, otherwise, it returns the input character.

Portability
towlower is C99.

No supporting OS subroutines are required.

2.29 towupper---translate wide-characters to upper case

#include <wctype.h>
wint_t towupper(wint_t c);

Returns
towupper returns the upper-case equivalent of c when it is a lower-case wide-character, otherwise, it returns the input character.

Portability
towupper is C99.

No supporting OS subroutines are required.

2.30 towctrans---extensible wide-character case mapping

#include <wctype.h>
wint_t towctrans(wint_t c, wctrans_t w);

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

Portability
towctrans is C99.

No supporting OS subroutines are required.

2.31 wctrans---get wide-character translation type

#include <wctype.h>
wctrans_t wctrans(const char *c);

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

Portability
wctrans is C99.

No supporting OS subroutines are required.

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

When using the small version of the C library, some functionality is removed from the input and output functions. In particular, no file opening or closing is supported, no buffering of output streams, no input streams and no floating point support. For more details on which functions are not supported, please see the entries under each function.

3.1 clearerr---clear file or stream error indicator		Clear file or stream error indicator
3.2 fclose---close a file		Close a file
3.3 feof---test for end of file		Test for end of file
3.4 ferror---test whether read/write error has occurred		Test whether read/write error has occurred
3.5 fflush---flush buffered file output		Flush buffered file output
3.6 fgetc---get a character from a file or stream		Get a character from a file or stream
3.7 fgetpos---record position in a stream or file		Record position in a stream or file
3.8 fgets---get character string from a file or stream		Get character string from a file or stream
3.9 fiprintf---format output to file (integer only)		Write formatted output to file (integer only)
3.10 fopen---open a file		Open a file
3.11 fdopen---turn open file into a stream		Turn an open file into a stream
3.12 fputc---write a character on a stream or file		Write a character on a stream or file
3.13 fputs---write a character string in a file or stream		Write a character string in a file or stream
3.14 fread---read array elements from a file		Read array elements from a file
3.15 freopen---open a file using an existing file descriptor		Open a file using an existing file descriptor
3.16 fseek, fseeko---set file position		Set file position
3.17 fsetpos---restore position of a stream or file		Restore position of a stream or file
3.18 ftell, ftello---return position in a stream or file		Return position in a stream or file
3.19 fwrite---write array elements		Write array elements from memory to a file or stream
3.20 getc---read a character (macro)		Get a character from a file or stream (macro)
3.21 getchar---read a character (macro)		Get a character from standard input (macro)
3.22 gets---get character string (obsolete, use fgets instead)		Get character string from standard input (obsolete)
3.23 getw---read a word (int)		Get a word (int) from a file or stream
3.24 iprintf---write formatted output (integer only)		Write formatted output (integer only)
3.25 mktemp, mkstemp---generate unused file name		Generate unused file name
3.26 perror---print an error message on standard error		Print an error message on standard error
3.27 putc---write a character (macro)		Write a character on a stream or file (macro)
3.28 putchar---write a character (macro)		Write a character on standard output (macro)
3.29 puts---write a character string		Write a character string on standard output
3.30 putw---write a word (int)		Write a word (int) to a file or stream
3.31 remove---delete a file's name		Delete a file's name
3.32 rename---rename a file		Rename a file
3.33 rewind---reinitialize a file or stream		Reinitialize a file or stream
3.34 setbuf---specify full buffering for a file or stream		Specify full buffering for a file or stream
3.35 setvbuf---specify file or stream buffering		Specify buffering for a file or stream
3.36 siprintf---write formatted output (integer only)		Write formatted output (integer only)
3.37 printf, fprintf, asprintf, sprintf, snprintf---format output		Write formatted output
3.38 scanf, fscanf, sscanf---scan and format input		Scan and format input
3.39 tmpfile---create a temporary file		Create a temporary file
3.40 tmpnam, tempnam---name for a temporary file		Generate name for a temporary file
3.41 vprintf, vfprintf, vsprintf---format argument list		Format variable argument list

3.1 clearerr---clear file or stream error indicator

#include <stdio.h>
void clearerr(FILE *fp);

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.

Small C Library
When using the small C library, these functions are not available.

3.2 fclose---close a file

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

Small C Library
When using the small C library, these functions are not available.

3.3 feof---test for end of file

#include <stdio.h>
int feof(FILE *fp);

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.

Small C Library
When using the small C library, these functions are not available.

3.4 ferror---test whether read/write error has occurred

#include <stdio.h>
int ferror(FILE *fp);

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.

Small C Library
When using the small C library, these functions are not available.

3.5 fflush---flush buffered file output

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

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.

Small C Library
When using the small C library, these functions are not available.

3.6 fgetc---get a character from a file or stream

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

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.

Small C Library
When using the small C library, these functions are not available.

3.7 fgetpos---record position in a stream or file

#include <stdio.h>
int fgetpos(FILE *fp, fpos_t *pos);
int _fgetpos_r(struct _reent *ptr, FILE *fp, fpos_t *pos);

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.

Small C Library
When using the small C library, these functions are not available.

3.8 fgets---get character string from a file or stream

#include <stdio.h>
char *fgets(char *buf, int n, FILE *fp);

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.

Small C Library
When using the small C library, these functions are not available.

3.9 fiprintf---format output to file (integer only)

#include <stdio.h>

int fiprintf(FILE *fd, const char *format, ...);

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.

Small C Library
When using the small C library, these functions are not available.

3.10 fopen---open a file

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

FILE *_fopen_r(void *reent, 
    const char *file, const char *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.

Small C Library
When using the small C library, these functions are not available.

3.11 fdopen---turn open file into a stream

#include <stdio.h>
FILE *fdopen(int fd, const char *mode);
FILE *_fdopen_r(void *reent,
    int fd, const char *mode);

Returns
File pointer or NULL, as for fopen.

Portability
fdopen is ANSI.

Small C Library
When using the small C library, these functions are not available.

3.12 fputc---write a character on a stream or file

#include <stdio.h>
int fputc(int ch, FILE *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.

3.13 fputs---write a character string in a file or stream

#include <stdio.h>
int fputs(const char *s, FILE *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.

3.14 fread---read array elements from a file

#include <stdio.h>
size_t fread(void *buf, size_t size, size_t count,
    FILE *fp);

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.

Small C Library
When using the small C library, these functions are not available.

3.15 freopen---open a file using an existing file descriptor

#include <stdio.h>
FILE *freopen(const char *file, const char *mode,
    FILE *fp);
FILE *_freopen_r(struct _reent *ptr, const char *file, 
    const char *mode, FILE *fp);

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.

Small C Library
When using the small C library, these functions are not available.

3.16 fseek, fseeko---set file position

#include <stdio.h>
int fseek(FILE *fp, long offset, int whence)
int fseeko(FILE *fp, off_t offset, int whence)
int _fseek_r(struct _reent *ptr, FILE *fp, 
    long offset, int whence)
int _fseeko_r(struct _reent *ptr, FILE *fp, 
    off_t offset, int whence)

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

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

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

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

See ftell/ftello to determine the current file position.

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

Portability
ANSI C requires fseek.

fseeko is defined by the Single Unix specification.

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

3.17 fsetpos---restore position of a stream or file

#include <stdio.h>
int fsetpos(FILE *fp, const fpos_t *pos);
int _fsetpos_r(struct _reent *ptr, FILE *fp, l
    const fpos_t *pos);

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.

Small C Library
When using the small C library, these functions are not available.

3.18 ftell, ftello---return position in a stream or file

#include <stdio.h>
long ftell(FILE *fp);
off_t ftello(FILE *fp);
long _ftell_r(struct _reent *ptr, FILE *fp);
off_t _ftello_r(struct _reent *ptr, FILE *fp);

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

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

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

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

ftello is defined by the Single Unix specification.

No supporting OS subroutines are required.

Small C Library
When using the small C library, these functions are not available.

3.19 fwrite---write array elements

#include <stdio.h>
size_t fwrite(const void *buf, size_t size,
    size_t count, FILE *fp);

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.

Small C Library
When using the small C library, these functions are not available.

3.20 getc---read a character (macro)

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

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.

Small C Library
When using the small C library, these functions are not available.

3.21 getchar---read a character (macro)

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

int _getchar_r(void *reent);

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.

Small C Library
When using the small C library, these functions are not available.

3.22 gets---get character string (obsolete, use fgets instead)

#include <stdio.h>

char *gets(char *buf);

char *_gets_r(void *reent, char *buf);

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.

Small C Library
When using the small C library, these functions are not available.

3.23 getw---read a word (int)

#include <stdio.h>
int getw(FILE *fp);

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

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

Supporting OS subroutines required: fread.

Small C Library
When using the small C library, these functions are not available.

3.24 iprintf---write formatted output (integer only)

#include <stdio.h>

int iprintf(const char *format, ...);

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.

Small C Library
When using the small C library, these functions are not available.

3.25 mktemp, mkstemp---generate unused file name

#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);

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.

Small C Library
When using the small C library, these functions are not available.

3.26 perror---print an error message on standard error

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

void _perror_r(void *reent, char *prefix);

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.

Small C Library
When using the small C library, these functions are not available.

3.27 putc---write a character (macro)

#include <stdio.h>
int putc(int ch, FILE *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 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.

3.28 putchar---write a character (macro)

#include <stdio.h>
int putchar(int ch);

int _putchar_r(void *reent, int ch);

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.

3.29 puts---write a character string

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

int _puts_r(void *reent, const char *s);

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.

3.30 putw---write a word (int)

#include <stdio.h>
int putw(int w, FILE *fp);

RETURNS Zero on success, EOF on failure.

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

Supporting OS subroutines required: fwrite.

Small C Library
When using the small C library, these functions are not available.

3.31 remove---delete a file's name

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

int _remove_r(void *reent, char *filename);

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.

Small C Library
When using the small C library, these functions are not available.

3.32 rename---rename a file

#include <stdio.h>
int rename(const char *old, const char *new);

int _rename_r(void *reent, 
    const char *old, const char *new);

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.

Small C Library
When using the small C library, these functions are not available.

3.33 rewind---reinitialize a file or stream

#include <stdio.h>
void rewind(FILE *fp);
void _rewind_r(struct _reent *ptr, FILE *fp);

Returns
rewind does not return a result.

Portability
ANSI C requires rewind.

No supporting OS subroutines are required.

Small C Library
When using the small C library, these functions are not available.