Red Hat newlib C Library:

Full Configuration

libc 1.13.0

January 30, 2004

[Top]

[Contents]

[Index]

[ ? ]

Red Hat newlib C Library: libc

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')
9. Reentrancy

10. Miscellaneous Macros and Functions
11. Character-set conversions (`iconv.h')
12. System Calls
13. Variable Argument Lists

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